Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

16

Sound

Classes

NXPlayStream

Inherits From:	NXSoundStream : Object

Initializing an NXPlayStream

- initOnDevice:anObject	Initializes a newly allocated NXPlayStream

Activating and Playing	

- (NXSoundDeviceError)activate	Prepares the NXPlayStream for playback	

- (NXSoundDeviceError)playBuffer:(void *)data	Plays a buffer of sound
size:(unsigned int)bytes
tag:(int)aTag

Setting Gain and Peak Detection

- (NXSoundDeviceError)setGainLeft:(float)leftAmp 	Sets the NXPlayStream's stereo gain
right:(float)rightAmp

- getGainLeft:(float *)leftScale 	Returns the NXPlayStream's gain by reference
right:(float *)rightScale

- (NXSoundDeviceError)getPeakLeft:(float *)leftAmp 
right:(float *)rightAmp	Returns the most recent peak amplitudes by reference

Delegate Methods

- soundStreamDidUnderrun:sender	Invoked when the sound driver underruns

NXRecordStream

Inherits From:	NXSoundStream : Object

Enqueueing Buffers

- (NXSoundDeviceError)recordSize:(unsigned int)bytes 
tag:(int)anInt	Enqueues a recording buffer

Requesting Data	

- (NXSoundDeviceError)sendRecordedDataToDelegate
	Sends the current buffer to the delegate

Delegate Methods

- soundStreamDidOverrun:sender	Invoked when the sound driver overruns

- soundStreamDidRecordData:(void *)data 	Delivers a buffer of recorded data
size:(unsigned int)numBytes 
forBuffer:(int)tag

NXSoundDevice

Inherits From:	Object

Conforms To:	NXSoundParameters

Initializing and Freeing an NXSoundDevice

- init	Initializes a newly allocated NXSoundDevice

- initOnHost:(const char *)hostName	Initializes a new NXSoundDevice on the given host

- free	Frees the NXSoundDevice

Using a Separate Thread	

+ (cthread_t)replyThread	Returns the thread in which driver messages are sent

+ setUseSeparateThread:(BOOL)flag	Sets whether a separate thread is used for driver messages

+ (BOOL)isUsingSeparateThread	Returns whether a separate thread is used for driver messages

+ setThreadThreshold:(int)threshold	Sets the message-reception threshold

+ (int)threadThreshold	Returns the message-reception threshold

Examining Ports

- (port_t)devicePort	Returns the port used to communicate with the sound driver

+ (port_t)replyPort	Returns the port to which the sound driver sends messages

- (port_t)streamOwnerPort	Returns the port used to connect to the sound driver

Identifying the Host Computer	

- (const char *)host	Returns the name of the computer on which the NXSoundDevice was initialized

Configuring the Object

- (id <NXSoundParameters>)parameters	Returns the object's parameters

- (NXSoundDeviceError)setParameters:(id <NXSoundParameters>)params

 - (BOOL)acceptsContinuousStreamSamplingRates

 - (NXSoundDeviceError)getStreamSamplingRatesLow:(float *)lowRate
    high:(float *)highRate;

 - (NXSoundDeviceError)getStreamSamplingRates:(const float **)rates
    count:(unsigned int *)numRates;

 - (NXSoundDeviceError)getStreamDataEncodings:(const NXSoundParameterTag **)encodings
    count:(unsigned int *)numEncodings

 - (unsigned int)streamChannelCountLimit

- (NXSoundDeviceError)setReserved:(BOOL)flag

	Sets whether the underlying device is reserved

 - (BOOL)isReserved	Returns whether the underlying device is reserved

+ setTimeout:(unsigned int)milliseconds	Sets the timeout period

+ (unsigned int)timeout	Returns the timeout period

Finding Peak Amplitudes

- (NXSoundDeviceError)getPeakLeft:(float *)leftAmp 
right:(float *)rightAmp	Returns the most recent peak amplitudes by reference

Controlling Streams

- abortStreams:sender	Aborts all streams connected to this NXSoundDevice

- pauseStreams:sender	Pauses all streams connected to this NXSoundDevice

- resumeStreams:sender	Resumes all streams connected to this NXSoundDevice

Handling errors

- (NXSoundDeviceError)lastError	Returns the most recent error

+ (const char *)textForError:(NXSoundDeviceError)errorCode
	Returns a string that describes the given error

NXSoundIn

Inherits From:	NXSoundDevice : Object

No methods

NXSoundOut

Inherits From:	NXSoundDevice : Object

No methods

NXSoundParameters

Inherits From:	Object

Conforms To:	NXSoundParameters (the protocol)

+ (const char *)localizedNameForParameter:(NXSoundParameterTag)ptag

- init

- initFromSound:aSound

- initFromSoundStruct:(SNDSoundStruct *)soundStruct

- (void)configureSoundStruct:(SNDSoundStruct *)soundStruct

NXSoundStream

Inherits From:	Object

Initializing and Freeing an NXSoundStream

- init	Initializes the NXSoundStream

- initOnDevice:aDevice withParameters:params	Initializes the NXSoundStream and connects it to aDevice

- free	Deactivates and frees the NXSoundStream.

Setting the Device	

- (NXSoundDeviceError)setDevice:aDevice	Connects the NXSoundStream to aDevice

- device	Returns the NXSoundDevice that the NXSoundStream is connected to. 

Activating and Deactivating	

- (NXSoundDeviceError)activate	Adds the NXSoundStream to the list of active streams

- (NXSoundDeviceError)deactivate	Aborts the NXSoundStream's current activity

Controlling the stream	

- abort:sender	Stops the NXSoundStream's playback or recording

- (NXSoundDeviceError)abortAtTime:(NXSoundStreamTime *)time
	Schedules the NXSoundStream to be aborted 

- pause:sender	Pauses the NXSoundStream's recording or playback

- (NXSoundDeviceError)pauseAtTime:(NXSoundStreamTime *)time
	Schedules the NXSoundStream to be paused

- resume:sender	Resumes the NXSoundStream's recording or playback 

- (NXSoundDeviceError)resumeAtTime:(NXSoundStreamTime *)time
	Schedules the NXSoundStream to be resumed

Querying the Object	

- (unsigned int)bytesProcessed	Returns the number of bytes of sound that the NXSoundStream has recorded or played

- (BOOL)isActive	Returns whether the NXSoundStream is currently activate

- (BOOL)isPaused	Returns whether the NXSoundStream is currently paused

- (port_t)streamPort	Returns the port used to connect to the sound driver 

- (NXSoundDeviceError)lastError	Returns the most recent sound device error

Assigning a Delegate	

- setDelegate:anObject	Sets the NXSoundStream's delegate.

- delegate	Returns the NXSoundStream's delegate.

Delegate Methods

- soundStream:sender didCompleteBuffer:(int)tag
	Invoked when the driver finishes playing or recording 

- soundStream:sender didStartBuffer:(int)tag	Invoked when the driver starts playing or recording

- soundStreamDidAbort:sender 	Invoked when the driver aborts the stream
deviceReserved:(BOOL)flag

- soundStreamDidPause:sender	Invoked when the NXSoundStream is paused

- soundStreamDidResume:sender	Invoked when the NXSoundStream is resumed

Sound

Inherits From:	Object

Conforms To:	soundkit/Sound.h

Creating and Freeing a Sound Object	

+ addName:(const char *)name 	Creates a Sound object from the sound resource named
fromBundle:(NXBundle *)aBundle	 	name in the NXBundle aBundle

+ addName:(const char *)name 	Creates a Sound object from the sectionName section
fromSection:(const char *)sectionName		of the sound segment in the application executable file

+ addName:(const char *)name 	Creates a Sound object from filename
fromSoundfile:(const char *)filename

- initFromSection:(const char *)sectionName	Creates a Sound object from the sectionName section of the sound segment in the application executable file

- initFromPasteboard:(Pasteboard *)thePboard	Creates a Sound object from the named pasteboard

- initFromSoundfile:(const char *)filename	Creates a Sound object from filename

- free	Frees the Sound object

Accessing the Sound Name Table

+ addName:(const char *)name sound:aSound	Assigns the name name to the Sound aSound and adds it to the name table

+ findSoundFor:(const char *)aName	Finds and returns the named Sound object

+ removeSoundForName:(const char *)name	Removes the named Sound from the name table

Accessing the Sound's Name	

- setName:(const char *)aName	Set's the Sound object's name

- (const char *)name	Return's the Sound object's name

Reading and Writing Sound Data	

- (int)readSoundfile:(const char *)filename	Replaces the Sound's data with that in filename

- readSoundFromStream:(NXStream *)stream	Replaces the Sound's data with that read from stream

- (int)writeSoundfile:(const char *)filename	Writes the Sound's data to filename

- writeSoundToStream:(NXStream *)stream	Writes the Sound's data to stream

- (int)writeToPasteboard:(Pasteboard *)pboard	Writes the Sound's data to the named pasteboard

Modifying Sound Data	

- (int)convertToFormat:(int)newFormat	Converts the Sound's data to the specified format,
samplingRate:(double)newRate		sampling rate, and channel count
channelCount:(int)newChannelCount

- (int)convertToFormat:(int)newFormat	Convert's the Sound's data to the specified format

- (int)setDataSize:(int)newDataSize	Set's the Sound's data as specified
dataFormat:(int)newDataFormat
samplingRate:(double)newSamplingRate
channelCount:(int)newChannelCount
infoSize:(int)newInfoSize

- setSoundStruct:(SNDSoundStruct *)aStruct  	Set's the Sound's sound structure
soundStructSize:(int)size

Querying the Sound Data	

- (SNDSoundStruct *)soundStruct	Returns the Sound's sound structure

- (int)soundStructSize	Gives the size of the Sound's sound structure

- (unsigned char *)data	Returns a pointer to the Sound's sound data

- (int)dataFormat	Returns the Sound's data format

- (int)dataSize	Returns the size in bytes of the Sound's data

- (int)channelCount	Returns the number of channels of sound

- (double)samplingRate	Returns the sound data's sampling rate

- (int)sampleCount	Returns the number of sample frames in the sound data

- (double)duration	Returns the sound's length in seconds

- (char *)info	Returns a pointer to the Sound's info string

- (int)infoSize	Returns the length in bytes of the Sound's info string

- (BOOL)isEmpty	Returns whether the Sound contains any sound data

- (BOOL)compatibleWith:aSound	Returns whether the Sound's format is compatiable with that of aSound

Recording and playing	

- (int)pause	Pauses the Sound's activity

- pause:sender	Pauses the Sound's activity

- (BOOL)isPlayable	Returns whether the Sound can be played

- (int)play	Plays the Sound

- play:sender	Plays the Sound

- (int)record	Records into the Sound

- record:sender	Records into the Sound

- (int)resume	Resumes the Sound's activity

- resume:sender	Resumes the Sound's activity

- (int)stop	Stops the Sound's activity

- stop:sender	Stops the Sound's activity

- (int)samplesProcessed	Returns the number of sample frames played or recorded 

- (int)status	Returns the Sound's activity code

- soundBeingProcessed	Returns self

- (SNDSoundStruct *)soundStructBeingProcessed
	Returns the sound structure that's being played or recorded

- (int)processingError	Returns the last error code that was generated

Editing Sound Data	

- (BOOL)isEditable	Returns whether the Sound's data can be edited

- (int)copySamples:aSound	Copies a range of samples from aSound into the receiver
at:(int)startSample
count:(int)sampleCount

- (int)copySound:aSound	Replaces the Sound's data with that in aSound

- (int)deleteSamples	Removes the Sound's data

- (int)deleteSamplesAt:(int)startSample 	Removes a range of samples from the Sound's data
count:(int)sampleCount

- (int)insertSamples:aSound at:(int)startSample	Inserts aSound's data into the Sound's data

- (BOOL)needsCompacting	Returns whether the Sound's data needs to be compacted

- (int)compactSamples	Compacts the Sound's data

Archiving the Object	

- finishUnarchiving	Invoked automatically after unarchiving

- read:(NXTypedStream *)stream	Unarchives the Sound from stream

- write:(NXTypedStream *)stream	Archives the Sound to stream

Accessing the Delegate	

- setDelegate:anObject	Sets the Sound's delegate object

- delegate	Returns the Sound's delegate

- tellDelegate:(SEL)theMessage	Sends theMessage to the delegate

Accessing the Sound Hardware	

+ getVolume:(float *)left :(float *)right	Returns the left and right volume settings by reference

+ setVolume:(float)left :(float)right	Sets the left and right volumes (0.0 to 1.0)

+ (BOOL)isMuted	Returns whether the internal speaker is muted

+ setMute:(BOOL)aFlag	Sets whether the internal speaker is muted

Delegate Methods

- didPlay:sender	Sent to the delegate when the Sound stops playing

- didRecord:sender	Sent to the delegate when the Sound stops recording

- hadError:sender	Sent to the delegate if an error occurs during recording or playback

- willPlay:sender	Sent to the delegate when the Sound begins to play

- willRecord:sender	Sent to the delegate when the Sound begins to record

SoundMeter

Inherits From:	View : Responder : Object

Initializing a SoundMeter

- initFrame:(const NXRect *)frameRect	Initializes the SoundMeter

Graphic Attributes	

- setBackgroundGray:(float)aValue	Sets the SoundMeter's background color

- (float)backgroundGray	Returns the SoundMeter's background color

- setForegroundGray:(float)aValue	Sets the SoundMeter's running bar color

- (float)foregroundGray	Returns the color of the running bar

- setBezeled:(BOOL)aFlag	Sets whether a bezeled border is drawn

- (BOOL)isBezeled	Returns whether the SoundMeter has a border

- setPeakGray:(float)aValue	Sets the SoundMeter's peak bubble color

- (float)peakGray	Returns the SoundMeter's peak bubble gray

Metering Attributes	

- setSound:aSound	Sets the SoundMeter's Sound object

- sound	Returns the Sound object that the SoundMeter is metering

- setFloatValue:(float)aValue	Sets the current running value

- setHoldTime:(float)seconds	Sets the SoundMeter's peak value hold time in seconds

- (float)holdTime	Returns the SoundMeter's peak hold time

Retrieving Meter Values	

- (float)floatValue	Returns the current running amplitude value

- (float)maxValue	Returns the maximum running value so far

- (float)minValue	Returns the minimum running value so far

- (float)peakValue	Returns the most recently detected peak value

Operating the Object	

- run:sender	Starts the SoundMeter running

- (BOOL)isRunning	Returns whether the SoundMeter is currently running

- stop:sender	Stops the SoundMeter's metering activity

Drawing the Object	

- drawCurrentValue	Draws the SoundMeter's running bar and peak bubble

- drawSelf:(const NXRect *)rects :(int)rectCount	Draws all the components of the SoundMeter

Archiving	

- read:(NXTypedStream *)aStream	Unarchives the SoundMeter by reading it from aStream

- write:(NXTypedStream *)aStream	Archives the SoundMeter by writing it to aStream

SoundView

Inherits From:	View : Responder : Object

Initializing and Freeing a SoundView	

- initFrame:(const NXRect *)frameRect	Initializes the SoundView

- free	Frees the SoundView 

Modifying the Object	

- scaleToFit	Fits the sound data within the current frame

- setBackgroundGray:(float)aGray	Sets the SoundView's background gray

- setBezeled:(BOOL)aFlag	Sets whether the SoundView has a bezeled border

- setContinuous:(BOOL)aFlag	Sets the state of continuous action messages.

- setDelegate:anObject	Sets the SoundView's delegate

- setDisplayMode:(int)aMode	Sets the SoundView's display mode

- setEnabled:(BOOL)aFlag	Enables or disables the SoundView

- setForegroundGray:(float)aGray	Sets the SoundView's foreground gray

- setOptimizedForSpeed:(BOOL)flag	Sets whether the SoundView's display mechanism is optimized 

- setSound:aSound	Sets the SoundView's Sound object

- sizeToFit	Resizes the SoundView's frame to maintain a constant reduction factor

Querying the Object	

- (float)backgroundGray	Returns the SoundView's background gray

- delegate	Returns the SoundView's delegate

- (int)displayMode	Returns the SoundView's display mode

- (float)foregroundGray	Returns the SoundView's foreground gray

- getSelection:(int *)firstSample 
size:(int *)sampleCount	Returns the selection by reference

- (BOOL)isAutoScale	Returns whether the SoundView is in autoscaling mode

- (BOOL)isBezeled	Returns whether the SoundView has a bezeled border

- (BOOL)isContinuous	Returns whether the SoundView responds to mouse-dragged events

- (BOOL)isEnabled	Returns whether the SoundView is enabled

- (BOOL)isOptimizedForSpeed	Returns whether the SoundView is optimized for speedy display

- (float)reductionFactor	Returns the SoundView's reduction factor

- sound	Returns the SoundView's Sound object.

Selecting and Editing the Sound Data

- copy:sender	Copies the current selection to the pasteboard

- cut:sender	Deletes the current selection

- delete:sender	Deletes the current selection

- mouseDown:(NXEvent *)theEvent	Allows a selection to be defined

- paste:sender	Replaces the current selection

- selectAll:sender	Creates a selection over the SoundView's entire sound

- setSelection:(int)firstSample size:(int)sampleCount
	Sets the selection

- (BOOL)isEditable	Returns whether the SoundView's data can be edited.

- setEditable:(BOOL)aFlag	Sets whether the SoundView can be edited

Pasteboard and Services Support	

- pasteboard:thePasteboard provideData:(const char *)pboardType
	Places the SoundView's sound on the given pasteboard

- readSelectionFromPasteboard:thePasteboard	Replaces the SoundView's current selection

- validRequestorForSendType:(NXAtom)sendType
 andReturnType:(NXAtom)returnType	You never invoke this method

- writeSelectionToPasteboard:thePasteboard 	Places a copy of the SoundView's current selection
types:(NXAtom *)pboardTypes 		on the given pasteboard

Modifying the Display Coordinates

- setAutoscale:(BOOL)aFlag	Sets the SoundView's automatic scaling mode

- setReductionFactor:(float)reductionFactor	Recomputes the size of the SoundView's frame 

Drawing the Object	

- drawSelf:(const NXRect *)rects :(int)rectCount	Displays the SoundView's sound data

- drawSamplesFrom:(int)first to:(int)last	Redisplays the given range of samples

- hideCursor	Hides the SoundView's cursor

- showCursor	Displays the SoundView's cursor

- sizeTo:(NXCoord)width :(NXCoord)height	Sets the width and height of the SoundView's frame

Responding to Events	

- (BOOL)acceptsFirstResponder	Returns YES

- becomeFirstResponder	Promotes the SoundView to first responder

- resignFirstResponder	Resigns the position of first responder

Performing the Sound Data	

- (BOOL)isPlayable	Returns whether the SoundView's sound can be played

- play:sender	Play the current selection

- record:sender	Replaces the SoundView's current selection

- pause:sender	Pauses the current playback or recording

- resume:sender	Resumes the current playback or recording

- stop:sender	Stops the SoundView's current recording or playback

- soundBeingProcessed	Returns the Sound object that's currently being played or recorded into

Archiving the Object	

- read:(void *)stream	Unarchives the SoundView by reading it from stream

- write:(void *)stream	Archives the SoundView by writing it to stream

Accessing the Delegate	

- didPlay:sender	Used to redirect delegate messages 

- didRecord:sender	Used to redirect delegate messages

- hadError:sender	Used to redirect delegate messages 

- tellDelegate:(SEL)theMessage	Sends theMessage to the SoundView's delegate 

- willPlay:sender	Used to redirect delegate messages

- willRecord:sender	Used to redirect delegate messages

Delegate Methods

- didPlay:sender	Sent to the delegate just after the SoundView is played.

- didRecord:sender	Sent to the delegate just after the SoundView is recorded into.

- hadError:sender	Sent to the delegate if an error is encountered .

- selectionChanged:sender	Sent to the delegate when the SoundView's selection changes.

- soundDidChange:sender	Sent to the delegate when the SoundView's sound is edited

- willFree:sender	Sent to the delegate when the SoundView is freed.

- willPlay:sender	Sent to the delegate just before the SoundView's sound is played.

- willRecord:sender	Sent to the delegate just before the SoundView's sound is recorded into.